<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>String literals</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Strings.xhtml" title="Strings"/>
    <link rel="next" href="Unicode.xhtml" title="Unicode character classes and conversions"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="String literals" epub:type="subchapter" id="String-literals">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">String literals</h2>
          </div>
        </div>
      </div>
      <p>Kaw support two syntaxes of string literals:
The traditional, portable, qdouble-quoted-delimited literals
like <code class="literal">"this"</code>;
and extended SRFI-109 quasi-literals like <code class="literal">&amp;{this}</code>.
</p>
      <section class="sect2" title="Simple string literals" epub:type="division" id="idm139667874965056">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Simple string literals</h3>
            </div>
          </div>
        </div>
        <div class="literallayout">
          <p><a id="idm139667874963984" class="indexterm"/><span id="meta-string"/><em class="replaceable"><code>string</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>"</strong></span></code><a class="link" href="String-literals.xhtml#meta-string-element"><em class="replaceable"><code>string-element</code></em></a><sup>*</sup><code class="literal"><span class="bold"><strong>"</strong></span></code><br/>
<a id="idm139667874959552" class="indexterm"/><span id="meta-string-element"/><em class="replaceable"><code>string-element</code></em> <code class="literal">::=</code> <span class="emphasis"><em>any character other than</em></span> <code class="literal"><span class="bold"><strong>"</strong></span></code> <span class="emphasis"><em>or</em></span> <code class="literal"><span class="bold"><strong>\</strong></span></code><br/>
    | <a class="link" href="String-literals.xhtml#meta-mnemonic-escape"><em class="replaceable"><code>mnemonic-escape</code></em></a> | <code class="literal"><span class="bold"><strong>\"</strong></span></code> | <code class="literal"><span class="bold"><strong>\\</strong></span></code><br/>
    | <code class="literal"><span class="bold"><strong>\</strong></span></code><a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup><a class="link" href="Lexical-syntax.xhtml#meta-line-ending"><em class="replaceable"><code>line-ending</code></em></a> <a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup><br/>
    | <a class="link" href="Lexical-syntax.xhtml#meta-inline-hex-escape"><em class="replaceable"><code>inline-hex-escape</code></em></a><br/>
<a id="idm139667874948208" class="indexterm"/><span id="meta-mnemonic-escape"/><em class="replaceable"><code>mnemonic-escape</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>\a</strong></span></code> | <code class="literal"><span class="bold"><strong>\b</strong></span></code> | <code class="literal"><span class="bold"><strong>\t</strong></span></code> | <code class="literal"><span class="bold"><strong>\n</strong></span></code> | <code class="literal"><span class="bold"><strong>\r</strong></span></code> | ... <span class="emphasis"><em>(see below)</em></span><br/>
</p>
        </div>
        <p>A string is written as a sequence of characters enclosed
within quotation marks (<code class="literal"><span class="bold"><strong>"</strong></span></code>).
Within a string literal, various escape sequence represent characters
other than themselves.
Escape sequences always start with a backslash (<code class="literal"><span class="bold"><strong>\</strong></span></code>):
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal"><span class="bold"><strong>\a</strong></span></code>
</dt>
            <dd>
              <p>Alarm (bell), <code class="literal">#\x0007</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\b</strong></span></code>
</dt>
            <dd>
              <p>Backspace, <code class="literal">#\x0008</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\e</strong></span></code>
</dt>
            <dd>
              <p>Escape, <code class="literal">#\x001B</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\f</strong></span></code>
</dt>
            <dd>
              <p>Form feed, <code class="literal">#\x000C</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\n</strong></span></code>
</dt>
            <dd>
              <p>Linefeed (newline), <code class="literal">#\x000A</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\r</strong></span></code>
</dt>
            <dd>
              <p>Return, <code class="literal">#\x000D</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\t</strong></span></code>
</dt>
            <dd>
              <p>Character tabulation, <code class="literal">#\x0009</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\v</strong></span></code>
</dt>
            <dd>
              <p>Vertical tab, <code class="literal">#\x000B</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\C-</strong></span></code><em class="replaceable"><code>x</code></em>
</dt>
            <dt class="term"><code class="literal"><span class="bold"><strong>\^</strong></span></code><em class="replaceable"><code>x</code></em>
</dt>
            <dd>
              <p>Returns the scalar value of <em class="replaceable"><code>x</code></em> masked (anded) with <code class="literal">#x9F</code>.
An alternative way to write the Ascii control characters:
For example <code class="literal">"\C-m"</code> or <code class="literal">"\^m"</code> is
the same as <code class="literal">"#\x000D"</code> (which the same as <code class="literal">"\r"</code>).
As a special case <code class="literal">\^?</code> is rubout (delete) (<code class="literal">\x7f;</code>).
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\x</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-hex-scalar-value"><em class="replaceable"><code>hex-scalar-value</code></em></a><code class="literal"><span class="bold"><strong>;</strong></span></code>
</dt>
            <dt class="term"><code class="literal"><span class="bold"><strong>\X</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-hex-scalar-value"><em class="replaceable"><code>hex-scalar-value</code></em></a><code class="literal"><span class="bold"><strong>;</strong></span></code>
</dt>
            <dd>
              <p>A hex encoding that gives the scalar value of a character.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\\</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-oct-digit"><em class="replaceable"><code>oct-digit</code></em></a><sup>+</sup>
</dt>
            <dd>
              <p>At most three octal digits that give the scalar value of a character.
(Historical, for C compatibility.)
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\u</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-hex-digit"><em class="replaceable"><code>hex-digit</code></em></a><sup>+</sup>
</dt>
            <dd>
              <p>Exactly four hex digits that give the scalar value of a character.
(Historical, for Java compatibility.)
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\M-</strong></span></code><em class="replaceable"><code>x</code></em>
</dt>
            <dd>
              <p>(Historical, for Emacs Lisp.)
Set the meta-bit (high-bit of single byte) of the following character <em class="replaceable"><code>x</code></em>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\|</strong></span></code>
</dt>
            <dd>
              <p>Vertical line, <code class="literal">#\x007c</code>.
(Not useful for string literals, but useful for symbols.)
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\"</strong></span></code>
</dt>
            <dd>
              <p>Double quote, <code class="literal">#\x0022</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\\</strong></span></code>
</dt>
            <dd>
              <p>Backslah, <code class="literal">#\005C</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>\</strong></span></code><a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup><a class="link" href="Lexical-syntax.xhtml#meta-line-ending"><em class="replaceable"><code>line-ending</code></em></a> <a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup>
</dt>
            <dd>
              <p>Nothing (ignored).  Allows you to split up a long string over multiple
lines; ignoring initial whitespace on the continuation lines allows
you to indent them.
</p>
            </dd>
          </dl>
        </div>
        <p>Except for a line ending, any character outside of an escape
sequence stands for itself in the string literal. A line ending
which is preceded by  <code class="literal"><span class="bold"><strong>\</strong></span></code><em class="replaceable"><code>intraline-whitespace</code></em><sup>*</sup>
expands to nothing (along with any trailing <em class="replaceable"><code>intraline-whitespace</code></em>),
and can be used to indent strings for improved legibility.
Any other line ending has the same effect as inserting a <code class="literal"><span class="bold"><strong>\n</strong></span></code>
character into the string.
</p>
        <p>Examples:
</p>
        <pre class="screen">"The word \"recursion\" has many meanings."
"Another example:\ntwo lines of text"
"Here’s text \
containing just one line"
"\x03B1; is named GREEK SMALL LETTER ALPHA."
</pre>
        <span id="string-quasi-literals"/>
      </section>
      <section class="sect2" title="String templates" epub:type="division" id="idm139667874889552">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">String templates</h3>
            </div>
          </div>
        </div>
        <p>The following syntax is a <em class="firstterm">string template</em> (also called
a string quasi-literal or
“<a class="ulink" href="http://en.wikipedia.org/wiki/Here_document" target="_top">here document</a>”):
</p>
        <pre class="screen">&amp;{Hello &amp;[name]!}
</pre>
        <p>Assuming the variable <code class="literal">name</code> evaluates to <code class="literal">"John"</code>
then the example evaluates to <code class="literal">"Hello John!"</code>.
</p>
        <p>The Kawa reader converts the above example to:
</p>
        <pre class="screen">($string$ "Hello " $&lt;&lt;$ name $&gt;&gt;$ "!")
</pre>
        <p>See the <a class="ulink" href="http://srfi.schemers.org/srfi-109/srfi-109.html" target="_top">SRFI-109</a>
specification for details.
</p>
        <div class="literallayout">
          <p><a id="idm139667874882992" class="indexterm"/><span id="meta-extended-string-literal"/><em class="replaceable"><code>extended-string-literal</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>&amp;{</strong></span></code> [<a class="link" href="String-literals.xhtml#meta-initial-ignored"><em class="replaceable"><code>initial-ignored</code></em></a>] <a class="link" href="String-literals.xhtml#meta-string-literal-part"><em class="replaceable"><code>string-literal-part</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>}</strong></span></code><br/>
<a id="idm139667874877456" class="indexterm"/><span id="meta-string-literal-part"/><em class="replaceable"><code>string-literal-part</code></em> <code class="literal">::=</code>  <span class="emphasis"><em>any character except</em></span> <code class="literal"><span class="bold"><strong>&amp;</strong></span></code>, <code class="literal"><span class="bold"><strong>{</strong></span></code> <span class="emphasis"><em>or</em></span> <code class="literal"><span class="bold"><strong>}</strong></span></code><br/>
    | <code class="literal"><span class="bold"><strong>{</strong></span></code> <a class="link" href="String-literals.xhtml#meta-string-literal-part"><em class="replaceable"><code>string-literal-part</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>}</strong></span></code><br/>
    | <a class="link" href="String-literals.xhtml#meta-char-ref"><em class="replaceable"><code>char-ref</code></em></a><br/>
    | <a class="link" href="String-literals.xhtml#meta-entity-ref"><em class="replaceable"><code>entity-ref</code></em></a><br/>
    | <a class="link" href="String-literals.xhtml#meta-special-escape"><em class="replaceable"><code>special-escape</code></em></a><br/>
    | <a class="link" href="String-literals.xhtml#meta-enclosed-part"><em class="replaceable"><code>enclosed-part</code></em></a><br/>
</p>
        </div>
        <p>You can use the plain <code class="literal">"<em class="replaceable"><code>string</code></em>"</code> syntax for
longer multiline strings, but <code class="literal">&amp;{<em class="replaceable"><code>string</code></em>}</code> has
various advantages.
The syntax is less error-prone because the start-delimiter is
different from the end-delimiter.  Also note that nested braces
are allowed: a right brace <code class="literal">}</code> is only an end-delimiter
if it is unbalanced, so you would seldom need to escape it:
</p>
        <pre class="screen">&amp;{This has a {braced} section.}
  ⇒ "This has a {braced} section."
</pre>
        <p>The escape character used for special characters is
<code class="literal"><span class="bold"><strong>&amp;</strong></span></code>.  This is compatible with XML syntax and <a class="link" href="XML-literals.xhtml" title="XML literals">XML literals</a>.
</p>
        <section class="sect3" title="Special characters" epub:type="division" id="idm139667874860704">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title">Special characters</h4>
              </div>
            </div>
          </div>
          <div class="literallayout">
            <p><a id="idm139667874859632" class="indexterm"/><span id="meta-char-ref"/><em class="replaceable"><code>char-ref</code></em> <code class="literal">::=</code><br/>
    <code class="literal"><span class="bold"><strong>&amp;#</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-digit"><em class="replaceable"><code>digit</code></em></a><sup>+</sup> <code class="literal"><span class="bold"><strong>;</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>&amp;#x</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-hex-digit"><em class="replaceable"><code>hex-digit</code></em></a><sup>+</sup>  <code class="literal"><span class="bold"><strong>;</strong></span></code><br/>
<a id="idm139667874852272" class="indexterm"/><span id="meta-entity-ref"/><em class="replaceable"><code>entity-ref</code></em> <code class="literal">::=</code><br/>
    <code class="literal"><span class="bold"><strong>&amp;</strong></span></code> <a class="link" href="String-literals.xhtml#meta-char-or-entity-name"><em class="replaceable"><code>char-or-entity-name</code></em></a> <code class="literal"><span class="bold"><strong>;</strong></span></code><br/>
<a id="idm139667874847856" class="indexterm"/><span id="meta-char-or-entity-name"/><em class="replaceable"><code>char-or-entity-name</code></em> <code class="literal">::=</code> <em class="replaceable"><code>tagname</code></em><br/>
</p>
          </div>
          <p>You can the standard XML syntax for character references, using
either decimal or hexadecimal values. The following string has two
instances of the Ascii escape character, as either decimal 27 or hex 1B:
</p>
          <pre class="screen">&amp;{&amp;#27;&amp;#x1B;} ⇒ "\e\e"
</pre>
          <p>You can also use the pre-defined XML entity names:
</p>
          <pre class="screen">&amp;{&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;} ⇒ "&amp; &lt; &gt; \" '"
</pre>
          <p>In addition, <code class="literal">&amp;lbrace;</code> <code class="literal">&amp;rbrace;</code> can be used for left and
right curly brace, though you don’t need them for balanced parentheses:
</p>
          <pre class="screen">&amp;{ &amp;rbrace;_&amp;lbrace; / {_} }  ⇒ " }_{ / {_} "
</pre>
          <p>You can use the <a class="ulink" href="http://www.w3.org/2003/entities/2007/w3centities-f.ent" target="_top">standard XML entity names</a>. For example:
</p>
          <pre class="screen">&amp;{L&amp;aelig;rdals&amp;oslash;yri}
  ⇒ "Lærdalsøyri"
</pre>
          <p>You can also use the standard R7RS character names <code class="literal">null</code>,
<code class="literal">alarm</code>, <code class="literal">backspace</code>, <code class="literal">tab</code>, <code class="literal">newline</code>, <code class="literal">return</code>,
<code class="literal">escape</code>, <code class="literal">space</code>, and <code class="literal">delete</code>.
For example:
</p>
          <pre class="screen">&amp;{&amp;escape;&amp;space;}
</pre>
          <p>The syntax <code class="literal">&amp;<em class="replaceable"><code>name</code></em>;</code> is actually syntactic sugar
(specifically reader syntax) to the variable reference
<code class="literal">$entity$:<em class="replaceable"><code>name</code></em></code>.
Hence you can also define your own entity names:
</p>
          <pre class="screen">(define $entity$:crnl "\r\n")
&amp;{&amp;crnl;} ⟹ "\r\n"
</pre>
        </section>
        <section class="sect3" title="Multiline string literals" epub:type="division" id="idm139667874833328">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title">Multiline string literals</h4>
              </div>
            </div>
          </div>
          <pre class="screen"><a id="idm139667874832240" class="indexterm"/><span id="meta-initial-ignored"/><em class="replaceable"><code>initial-ignored</code></em> <code class="literal">::=</code>
    <a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup> <a class="link" href="Lexical-syntax.xhtml#meta-line-ending"><em class="replaceable"><code>line-ending</code></em></a> <a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>&amp;|</strong></span></code>
<a id="idm139667874826448" class="indexterm"/><span id="meta-special-escape"/><em class="replaceable"><code>special-escape</code></em> <code class="literal">::=</code>
    <a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>&amp;|</strong></span></code>
  | <code class="literal"><span class="bold"><strong>&amp;</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-nested-comment"><em class="replaceable"><code>nested-comment</code></em></a>
  | <code class="literal"><span class="bold"><strong>&amp;-</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-intraline-whitespace"><em class="replaceable"><code>intraline-whitespace</code></em></a><sup>*</sup> <a class="link" href="Lexical-syntax.xhtml#meta-line-ending"><em class="replaceable"><code>line-ending</code></em></a>
</pre>
          <p>A line-ending directly in the text is becomes a newline,
as in a simple string literal:
</p>
          <pre class="screen">(string-capitalize &amp;{one two three
uno dos tres
}) ⇒ "One Two Three\nUno Dos Tres\n"
</pre>
          <p>However, you have extra control over layout.
If the string is in a nested expression, it is confusing
(and ugly) if the string cannot be indented to match
the surrounding context. The indentation marker <code class="literal"><span class="bold"><strong>&amp;|</strong></span></code>
is used to mark the end of insignificant initial whitespace.
The <code class="literal">&amp;|</code> characters and all the preceding whitespace are removed.
In addition, it also suppresses an initial newline.  Specifically,
when the initial left-brace is followed by optional (invisible)
intraline-whitespace, then a newline, then optional
intraline-whitespace (the indentation), and finally the indentation
marker <code class="literal">&amp;|</code> - all of which is removed from the output.
Otherwise the <code class="literal">&amp;|</code> only removes initial intraline-whitespace
on the same line (and itself).
</p>
          <pre class="screen">(write (string-capitalize &amp;{
     &amp;|one two three
     &amp;|uno dos tres
}) out)
    ⇒ <span class="emphasis"><em>prints</em></span> "One Two Three\nUno Dos Tres\n"
</pre>
          <p>As a matter of style, all of the indentation lines should line up.
It is an error if there are any non-whitespace characters between
the previous newline and the indentation marker.
It is also an error to write an indentation marker before the
first newline in the literal.
</p>
          <p>The line-continuation marker <code class="literal"><span class="bold"><strong>&amp;-</strong></span></code> is used to suppress a newline:
</p>
          <pre class="screen">&amp;{abc&amp;-
  def} ⇒ "abc  def"
</pre>
          <p>You can write a <code class="literal">#|...|#</code>-style comment following a <code class="literal">&amp;</code>.
This could be useful for annotation, or line numbers:
</p>
          <pre class="screen">&amp;{&amp;#|line 1|#one two
  &amp;#|line 2|# three
  &amp;#|line 3|#uno dos tres
} ⇒ "one two\n three\nuno dos tres\n"
</pre>
        </section>
        <section class="sect3" title="Embedded expressions" epub:type="division" id="idm139667874808736">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title">Embedded expressions</h4>
              </div>
            </div>
          </div>
          <pre class="screen"><a id="idm139667874807664" class="indexterm"/><span id="meta-enclosed-part"/><em class="replaceable"><code>enclosed-part</code></em> <code class="literal">::=</code>
    <code class="literal"><span class="bold"><strong>&amp;</strong></span></code> <a class="link" href="String-literals.xhtml#meta-enclosed-modifier"><em class="replaceable"><code>enclosed-modifier</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>[</strong></span></code> <a class="link" href="Primitive-expression-syntax.xhtml#meta-expression"><em class="replaceable"><code>expression</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>]</strong></span></code>
  | <code class="literal"><span class="bold"><strong>&amp;</strong></span></code> <a class="link" href="String-literals.xhtml#meta-enclosed-modifier"><em class="replaceable"><code>enclosed-modifier</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Primitive-expression-syntax.xhtml#meta-expression"><em class="replaceable"><code>expression</code></em></a><sup>+</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code>
</pre>
          <p>An embedded expression has the form <code class="literal">&amp;[<em class="replaceable"><code>expression</code></em>]</code>.
It is evaluated, the result converted to a string (as by <code class="literal">display</code>),
and the result added in the result string.
(If there are multiple expressions, they are all evaluated and
the corresponding strings inserted in the result.)
</p>
          <pre class="screen">&amp;{Hello &amp;[(string-capitalize name)]!}
</pre>
          <p>You can leave out the square brackets when the expression
is a parenthesized expression:
</p>
          <pre class="screen">&amp;{Hello &amp;(string-capitalize name)!}
</pre>
        </section>
        <section class="sect3" title="Formatting" epub:type="division" id="idm139667874793168">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title">Formatting</h4>
              </div>
            </div>
          </div>
          <pre class="screen"><a id="idm139667874792096" class="indexterm"/><span id="meta-enclosed-modifier"/><em class="replaceable"><code>enclosed-modifier</code></em> <code class="literal">::=</code>
  <code class="literal"><span class="bold"><strong>~</strong></span></code> <em class="replaceable"><code>format-specifier-after-tilde</code></em>
</pre>
          <p>Using <a class="link" href="Format.xhtml" title="Formatted Output (Common-Lisp-style)"><code class="literal">format</code></a> allows finer-grained control over the
output, but a problem is that the association between format
specifiers and data expressions is positional, which is hard-to-read
and error-prone. A better solution places the specifier adjacant to
the data expression:
</p>
          <pre class="screen">&amp;{The response was &amp;~,2f(* 100.0 (/ responses total))%.}
</pre>
          <p>The following escape forms are equivalent to the corresponding
forms withput the <code class="literal"><span class="bold"><strong>~</strong></span></code><em class="replaceable"><code>fmt-spec</code></em>, except the
expression(s) are formatted using <code class="literal">format</code>:
</p>
          <div class="literallayout">
            <p><code class="literal"><span class="bold"><strong>&amp;~</strong></span></code><em class="replaceable"><code>fmt-spec</code></em><code class="literal"><span class="bold"><strong>[</strong></span></code><em class="replaceable"><code>expression</code></em><sup>*</sup><code class="literal"><span class="bold"><strong>]</strong></span></code> <br/>
</p>
          </div>
          <p>Again using parentheses like this:
</p>
          <div class="literallayout">
            <p><code class="literal"><span class="bold"><strong>&amp;~</strong></span></code><em class="replaceable"><code>fmt-spec</code></em><code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>expression</code></em><sup>+</sup><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
</p>
          </div>
          <p>is equivalent to:
</p>
          <div class="literallayout">
            <p><code class="literal"><span class="bold"><strong>&amp;~</strong></span></code><em class="replaceable"><code>fmt-spec</code></em><code class="literal"><span class="bold"><strong>[(</strong></span></code><em class="replaceable"><code>expression</code></em><sup>+</sup><code class="literal"><span class="bold"><strong>)]</strong></span></code><br/>
</p>
          </div>
          <p>The syntax of <code class="literal">format</code> specifications is arcane, but it allows you
to do some pretty neat things in a compact space.
For example to include <code class="literal">"_"</code> between each element of
the array <code class="literal">arr</code> you can use the <code class="literal">~{...~}</code> format speciers:
</p>
          <pre class="screen">(define arr [5 6 7])
&amp;{&amp;~{&amp;[arr]&amp;~^_&amp;~}} ⇒ "5_6_7"
</pre>
          <p>If no format is specified for an enclosed expression,
the that is equivalent to a <code class="literal">~a</code> format specifier,
so this is equivalent to:
</p>
          <pre class="screen">&amp;{&amp;~{&amp;~a[arr]&amp;~^_&amp;~}} ⇒ "5_6_7"
</pre>
          <p>which is in turn equivalent to:
</p>
          <pre class="screen">(format #f "~{~a~^_~}" arr)
</pre>
          <p>The fine print that makes this work:
If there are multiple expressions in a <code class="literal">&amp;[...]</code> with
no format specifier then there is an implicit <code class="literal">~a</code> for
each expression.
On the other hand, if there is an explicit format specifier,
it is not repeated for each enclosed expression: it appears
exactly once in the effective format string, whether
there are zero, one, or many expressions.
</p>
        </section>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="String-literals.xhtml#idm139667874965056">Simple string literals</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="String-literals.xhtml#idm139667874889552">String templates</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Characters-and-text.xhtml">Characters and text</a></p>
        <p>
        Previous: <a accesskey="p" href="Strings.xhtml">Strings</a></p>
        <p>
        Next: <a accesskey="n" href="Unicode.xhtml">Unicode character classes and conversions</a></p>
      </div>
    </footer>
  </body>
</html>
